home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / share / perl5 / Carp / Clan.pod < prev   
Encoding:
Text File  |  2009-10-24  |  3.7 KB  |  96 lines
  1.  
  2. =head1 NAME
  3.  
  4. Carp::Clan - Report errors from perspective of caller of a "clan" of modules
  5.  
  6. =head1 SYNOPSIS
  7.  
  8.  carp    - warn of errors (from perspective of caller)
  9.  
  10.  cluck   - warn of errors with stack backtrace
  11.  
  12.  croak   - die of errors (from perspective of caller)
  13.  
  14.  confess - die of errors with stack backtrace
  15.  
  16.     use Carp::Clan qw(^MyClan::);
  17.     croak "We're outta here!";
  18.  
  19.     use Carp::Clan;
  20.     confess "This is how we got here!";
  21.  
  22. =head1 DESCRIPTION
  23.  
  24. This module is based on "C<Carp.pm>" from Perl 5.005_03. It has been
  25. modified to skip all package names matching the pattern given in
  26. the "use" statement inside the "C<qw()>" term (or argument list).
  27.  
  28. Suppose you have a family of modules or classes named "Pack::A",
  29. "Pack::B" and so on, and each of them uses "C<Carp::Clan qw(^Pack::);>"
  30. (or at least the one in which the error or warning gets raised).
  31.  
  32. Thus when for example your script "tool.pl" calls module "Pack::A",
  33. and module "Pack::A" calls module "Pack::B", an exception raised in
  34. module "Pack::B" will appear to have originated in "tool.pl" where
  35. "Pack::A" was called, and not in "Pack::A" where "Pack::B" was called,
  36. as the unmodified "C<Carp.pm>" would try to make you believe C<:-)>.
  37.  
  38. This works similarly if "Pack::B" calls "Pack::C" where the
  39. exception is raised, etcetera.
  40.  
  41. In other words, this blames all errors in the "C<Pack::*>" modules
  42. on the user of these modules, i.e., on you. C<;-)>
  43.  
  44. The skipping of a clan (or family) of packages according to a pattern
  45. describing its members is necessary in cases where these modules are
  46. not classes derived from each other (and thus when examining C<@ISA>
  47. - as in the original "C<Carp.pm>" module - doesn't help).
  48.  
  49. The purpose and advantage of this is that a "clan" of modules can work
  50. together (and call each other) and throw exceptions at various depths
  51. down the calling hierarchy and still appear as a monolithic block (as
  52. though they were a single module) from the perspective of the caller.
  53.  
  54. In case you just want to ward off all error messages from the module
  55. in which you "C<use Carp::Clan>", i.e., if you want to make all error
  56. messages or warnings to appear to originate from where your module
  57. was called (this is what you usually used to "C<use Carp;>" for C<;-)>),
  58. instead of in your module itself (which is what you can do with a
  59. "die" or "warn" anyway), you do not need to provide a pattern,
  60. the module will automatically provide the correct one for you.
  61.  
  62. I.e., just "C<use Carp::Clan;>" without any arguments and call "carp"
  63. or "croak" as appropriate, and they will automatically defend your
  64. module against all blames!
  65.  
  66. In other words, a pattern is only necessary if you want to make
  67. several modules (more than one) work together and appear as though
  68. they were only one.
  69.  
  70. =head2 Forcing a Stack Trace
  71.  
  72. As a debugging aid, you can force "C<Carp::Clan>" to treat a "croak" as
  73. a "confess" and a "carp" as a "cluck". In other words, force a detailed
  74. stack trace to be given. This can be very helpful when trying to
  75. understand why, or from where, a warning or error is being generated.
  76.  
  77. This feature is enabled either by "importing" the non-existent symbol
  78. 'verbose', or by setting the global variable "C<$Carp::Clan::Verbose>"
  79. to a true value.
  80.  
  81. You would typically enable it by saying
  82.  
  83.     use Carp::Clan qw(verbose);
  84.  
  85. Note that you can both specify a "family pattern" and the string "verbose"
  86. inside the "C<qw()>" term (or argument list) of the "use" statement, but
  87. consider that a pattern of packages to skip is pointless when "verbose"
  88. causes a full stack trace anyway.
  89.  
  90. =head1 BUGS
  91.  
  92. The "C<Carp::Clan>" routines don't handle exception objects currently.
  93. If called with a first argument that is a reference, they simply
  94. call "C<die()>" or "C<warn()>", as appropriate.
  95.  
  96.